library(raveio)
project_demo <- as_rave_project("demo", strict = FALSE)
if(!"DemoSubject" %in% project_demo$subjects()) {
# missing demo subject, install
message("Missing `DemoSubject`. Downloading...")
install_subject("DemoSubject")
}Prerequisites
This post assumes that you have already imported subject’s imaging data to RAVE and finished the electrode localization. If you haven’t done so, please check (TODO) for instructions.
This post uses default demo subject. Please run the following code block
1. Simple 3D viewer
Library raveio provides simple high-level function rave_brain to load 3D brain object.
brain <- raveio::rave_brain("demo/DemoSubject")
# See the output to the right for what's inside of the brain object
brainSubject - DemoSubject
Transforms:
- FreeSurfer TalXFM [from scanner to MNI305]:
[,1] [,2] [,3] [,4]
[1,] 1.071608 -0.069364 0.003839 -5.186203
[2,] -0.033422 1.293478 0.133732 -26.001312
[3,] 0.039658 -0.231380 1.268464 -21.980759
[4,] 0.000000 0.000000 0.000000 1.000000
- Torig [Voxel IJK/CRS to FreeSurfer space tkrRAS, vox2ras-tkr]
[,1] [,2] [,3] [,4]
[1,] -1 0 0 128
[2,] 0 0 1 -128
[3,] 0 -1 0 128
[4,] 0 0 0 1
- Norig [Voxel IJK/CRS to Scanner space, vox2ras]
[,1] [,2] [,3] [,4]
[1,] -1 0 0 131.6145
[2,] 0 0 1 -127.5000
[3,] 0 -1 0 127.5000
[4,] 0 0 0 1.0000
- Scanner origin in FreeSurfer tkrRAS coordinate
[1] -3.614471 -0.500000 0.500000
- FreeSurfer RAS to MNI305, vox2vox-MNI305
[,1] [,2] [,3] [,4]
[1,] 1.071608 -0.069364 0.003839 -1.349508
[2,] -0.033422 1.293478 0.133732 -25.542242
[3,] 0.039658 -0.231380 1.268464 -22.587338
[4,] 0.000000 0.000000 0.000000 1.000000
Surface information (total count 1)
pial [ fs ]
Volume information (total count 1)
T1
Use brain$plot(<your arguments...>) to show the viewer:
brain$plot()
2. Render electrodes with values
brain$set_electrode_values(table_or_path) allows users to load a data table and render electrodes with colors. Users can create a csv table using Excel or their favorite programming languages, as long as the table follows the following format:
| Subject | Electrode | varname* |
|---|---|---|
| DemoSubject | 1 | 0.25 |
| DemoSubject | 14 | -0.4 |
| … | … | … |
The column names are case-sensitive
Subjectis the subject codeElectrodeis the electrode channel number (integer)varname*can be almost anything (give it a meaningful name, for e.g.,Power,Cluster, …) that you would like to show, and the values can be either numeric or categorical- The variable name is recommended to only contain letters and digits. For example,
BetaBandPowerseems to be a good idea, while names like75-150 Hzshould be avoided - The variable values must not be numerical if the intent is categorical. For example cluster values such as
1,2,3, … should be avoided and users should useCluster 1,Cluster 2,Cluster 3, …, orA,B,C, … instead
- The variable name is recommended to only contain letters and digits. For example,
# Method 1: `csv_path` is the string of path to the csv
brain$set_electrode_values(csv_path)
# Method 2: use data frame
table <- read.csv(csv_path)
brain$set_electrode_values(table)
brain$plot()
3. Render options
brain$plot allows users to provide render options to change the following components:
- Color palette
- Default value ranges (for continuous data)
- Control panels
Here’s an example
# Load brain
brain <- raveio::rave_brain("demo/DemoSubject")
# Set values with 2 variables: `ContinuousVal` and `CategoricalVal`
brain$set_electrode_values(
data.frame(
Subject = "DemoSubject",
Electrode = c(13:16,24,73:80),
ContinuousVal = rnorm(13),
CategoricalVal = sample(letters[1:4], size = 13, replace = TRUE),
PValue = c(0.15, 0.5, 0.9, 0.01, 0.05, 0.45, 0.8,
0.68, 0.6, 0.33, 0.001, 0.36, 0.83)
)
)
# Plot brain with options
brain$plot(
# change color palettes: each variable requires a palette (if not default)
palettes = list(
# discrete values require each category to be filled with a
# color. The order is alphabetic
CategoricalVal = c("red", "blue", "green"),
# continuous values requires at least 2 key colors
ContinuousVal = c("white", "purple"),
# p-value is not linearly scaled, R provides `colorRampPalette`
# to generate non-linear color palette from at least
# 3 key colors.
# This example used 5 key colors with bias = 2 so the
PValue = colorRampPalette(
c("red", "yellow", "cyan", "gray", "gray"), bias = 2
)(100)
),
# Change value range: sets the value range for variables that have
# bounded ranges, such as p-values
value_ranges = list(
# p-value should range from 0-1
PValue = c(0, 1),
# We also want to trim the `ContinuousVal` to 95% CI
ContinuousVal = c(-2, 2)
),
# Set initial controller status
controllers = list(
# Display p-value
"Display Data" = "PValue",
# Overlay atlases from side canvas
"Voxel Type" = "aparc_aseg",
"Voxel Display" = "side camera",
# Overlay axial slices with surfaces
"Overlay Axial" = TRUE,
# Set surface opacity
"Left Opacity" = 0.4,
"Left Mesh Clipping" = 0.3,
"Right Opacity" = 0.4,
"Right Mesh Clipping" = 0.3,
# Electrode outline
"Outlines" = "on",
"Translucent" = "contact+outline",
# Background color and camera position
"Background Color" = "#000000",
"Camera Position" = "superior"
),
# Custom javascript for advanced users
custom_javascript = r"[
app.$wrapper.parentNode.style.width="100%";
app.$wrapper.parentNode.style.height="600px";
app.canvas.side_width = 160;
app.canvas.sideCanvasList.coronal.reset();
app.canvas.sideCanvasList.axial.reset();
app.canvas.sideCanvasList.sagittal.reset();
app.resize()
]"
)Key Documentations
Function rave_brain
Load ‘FreeSurfer’ or ‘AFNI/SUMA’ brain from ‘RAVE’
rave_brain
Description
Create 3D visualization of the brain and visualize with modern web browsers
Usage
rave_brain(
subject,
surfaces = "pial",
use_141 = TRUE,
recache = FALSE,
clean_before_cache = FALSE,
compute_template = FALSE,
usetemplateifmissing = FALSE,
include_electrodes = TRUE
)
Arguments
subject
|
character, list, or |
surfaces
|
one or more brain surface types from |
use_141
|
whether to use ‘AFNI/SUMA’ standard 141 brain |
recache
|
whether to re-calculate cache; only should be used when the original ‘FreeSurfer’ or ‘AFNI/SUMA’ files are changed; such as new files are added |
clean_before_cache
|
whether to clean the original cache before |
compute_template
|
whether to compute template mappings; useful when template mapping with multiple subjects are needed |
usetemplateifmissing
|
whether to use template brain when the subject brain files are missing. If set to true, then a template (usually ‘N27’) brain will be displayed as an alternative solution, and electrodes will be rendered according to their |
include_electrodes
|
whether to include electrode in the model; default is true |
Value
A ‘threeBrain’ instance if brain is found or usetemplateifmissing is set to true; otherwise returns NULL
Examples
# Please make sure DemoSubject is correctly installed
# The subject is ~1GB from Github
if(interactive()){
brain <- rave_brain("demo/DemoSubject")
if( !is.null(brain) ) { brain$plot() }
}